<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The main functions</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="Windows API, Winapi, Win32, C, main functions">
<meta name="description" content="In this part of the Winapi tutorial, we 
will talk about main functions.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container2">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content2">


<a href="/" title="Home">Home</a>&nbsp;
<a href="..">Contents</a>


<h1>Main functions</h1>


<p>
In this part of the Winapi tutorial, we will talk about main
functions. 
</p>
                                                          
<div class="big_hor">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* big_horizontal */
google_ad_slot = "2904953388";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<h2>The main() function prototypes</h2>

<p>
The main() function is an entry point to a C program. 
However, it is not the first program to run. When the entry point
is main(), the program execution actually begins in a function called 
mainCRTStartup(). This function is located in the C runtime library.
It initializes things like the memory manager, file I/O support, 
and the argv parameter. After that, the mainCRTStartup() function 
will call the main() function.
</p>

<pre>
int main(void);
int main(int argc, char **argv);
int main(int argc, char *argv[]);
</pre>

<p>
These are the function prototypes for the main() function for
the classic console program.
</p>

<pre class="code">
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;

int main(int argc, char **argv) 
{
    puts("This is a classic C program.");

    return EXIT_SUCCESS;
}
</pre>

<p>
The above source code presents an example of a classic
C program.   
</p>


<h2>The wmain function prototypes</h2>

<p>
The previous main function prototypes could receive only ASCII characters.
If we want a program that could receive wide characters from the command line,
we will use the wmain function prototypes.
</p>

<pre>
int wmain(void);
int wmain(int argc, wchar_t **argv);
int wmain(int argc, wchar_t *argv[]);
</pre>

<p>
The above wmain function prototypes take wchar_t characters on the command line.
When we use these prototypes, the execution begins in a function called 
wmainCRTStartup() which will later call the wmain() function. 
</p>

<pre class="code">
#include &lt;windows.h&gt;
#include &lt;wchar.h&gt;

int wmain(int argc, wchar_t **argv) 
{
    PDWORD cChars = NULL;
    HANDLE std = GetStdHandle(STD_OUTPUT_HANDLE);   
    
    if (std == INVALID_HANDLE_VALUE) {
        wprintf(L"Cannot retrieve standard output handle\n (%d)", 
            GetLastError());
    }
 
    WriteConsoleW(std, argv[1], wcslen(argv[1]), cChars, NULL);
 
    return EXIT_SUCCESS;
}
</pre>

<p>
We have a wmain() function which can receive wide characters.
The example prints the first argument of the console program.
</p>

<pre class="explanation">
int wmain(int argc, wchar_t **argv) {
</pre>

<p>
The <code>wchar_t</code> type of the second parameter of the wmain() function 
tells us, that the program input is in wide characters. 
</p>

<pre class="explanation">
HANDLE std = GetStdHandle(STD_OUTPUT_HANDLE);    
</pre>

<p>
The <code>GetStdHandle()</code> function returns a handle to a 
standard output. 
</p>

<pre class="explanation">
if (std == INVALID_HANDLE_VALUE) {
    wprintf(L"Cannot retrieve standard output handle\n (%d)", 
        GetLastError());
} 
</pre>

<p>
In case of an error, we receive a <code>INVALID_HANDLE_VALUE</code>
return code. For this situation we print an error message.
</p>

<pre class="explanation">
WriteConsoleW(std, argv[1], wcslen(argv[1]), cChars, NULL);
</pre>

<p>
We use the <code>WriteConsoleW()</code> function to write to console
in wide characters. 
</p>

<pre>
C:\winapi\examples2\system\Main2>Main2.exe компилятор
компилятор
</pre>

<p>
We add a russian word (compiler) as a parameter to our program. The 
program simply prints the parameter back to the console. Note that in
order to see correct characters, we need to change the default font
of the console to Lucida Console. We need a true type font to display
wide characters correctly.
</p>

<h2>The _tmain function prototypes</h2>

<p>
The <code>_tmain()</code> function is a Microsoft extension. It enables 
programmers to easily create both ANSI and UNICODE builds of their programs.
It is a C macro that translates to <code>wmain()</code> or <code>main()</code> 
functions, depending whether the _UNICODE constant is defined or not. It was 
common in the past to create both ANSI and UNICODE builds. Nowadays, many 
programmers recommend to create only unicode programs. This is also what we 
will do in our tutorial. We will create mostly unicode programs. 
</p>

<pre>
int _tmain(void);
int _tmain(int argc, TCHAR **argv);
int _tmain(int argc, TCHAR *argv[]);
</pre>

<p>
These are the <code>_tmain</code> function prototypes. The TCHAR macro 
translates either to <code>char</code> or to <code>wchar_t</code>. It is 
controlled by the UNICODE constatnt.
</p>

<pre class="code">
#define _UNICODE
#define UNICODE

#include &lt;windows.h&gt;
#include &lt;tchar.h&gt;

int _tmain(int argc, TCHAR *argv[]) 
{
    PDWORD cChars = NULL;
    HANDLE std = GetStdHandle(STD_OUTPUT_HANDLE);

    if (std == INVALID_HANDLE_VALUE) {
        _tprintf(L"Cannot retrieve standard output handle\n (%d)", 
            GetLastError());
    }  
        
    WriteConsole(std, argv[1], _tcslen(argv[1]), cChars, NULL);

    return EXIT_SUCCESS;
}
</pre>

<p>
To compile this example, we need to have Microsoft extensions enabled.
To enable Microsoft extensions, go to Project, Project options..., Compiler
tab. In the Options part, click on the Enable Microsoft extensions check box.
</p>

<pre class="explanation">
#define _UNICODE
#define UNICODE
</pre>

<p>
Here we define two constants. These definitions mean, that we are going to 
build unicode program. They translate C macros in C runtime and
Windows header files.  The _UNICODE constant translates macros in the C runtime.
(These macros start with an underscore.) The UNICODE constant translates 
macros in the Windows header files. 
</p>

<pre class="explanation">
#include &lt;windows.h&gt;
</pre>

<p>
In this header file we have the definition of the TCHAR macro. It 
is affected by the UNICODE constant. 
</p>

<pre class="explanation">
#include &lt;tchar.h&gt;
</pre>

<p>
We must include this header file for the _tmain and _tcslen macros.
They are translated depending on the _UNICODE macro.
</p>


<pre class="explanation">
int _tmain(int argc, TCHAR *argv[]) {
</pre>

<p>
The <code>_tmain()</code> function translates in our case to </code>wmain()</code> 
and the TCHAR to <code>wchar_t</code>. 
</p>

<pre class="explanation">
WriteConsole(std, argv[1], _tcslen(argv[1]), cChars, NULL);
</pre>

<p>
The <code>WriteConsole()</code> function prints output to the console.
The function is transleted to <code>WriteConsoleW()</code>. The 
<code>_tcslen</code> macro is translated to <code>wcslen()</code> function. 
</p>

<pre>
C:\winapi\examples2\system\Main3>Main3.exe "операционная система"
операционная система
</pre>

<p>
The program takes another russian word (operating system) as a parameter
and prints it to the console.
</p>


<h2>The WinMain function prototypes</h2>

<p>
So far we had console main functions. For graphical user interface development, 
we have to use one of the WinMain function prototypes. 
</p>


<pre class="explanation">
int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    PWSTR pCmdLine, int nCmdShow);
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    LPSTR lpCmdLine, int nCmdShow);
int APIENTRY _tWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    LPTSTR lpCmdLine, int nCmdShow);
</pre>

<p>
These three function prototypes are used for entry points for 
Windows GUI applications. The <code>wWinMain()</code> function pCmdLine 
parameter contains the command-line arguments as a Unicode string. The 
<code>WinMain()</code> function pCmdLine parameter contains the command-line 
arguments as an ANSI string. The <code>_tWinMain</code> is a C macro that 
translates to other two function prototypes, depending whether the _UNICODE 
constant is defined or not.
</p>

<p>
When the entry point is WinMain(), the execution of the program begins
in WinMainCRTStartup(). In case of wWinMain(), the execution begins in
wWinMainCRTStartup(). 
</p>
             
<pre class="code">
#include &lt;windows.h&gt;

int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
               PWSTR szCmdLine, int CmdShow)
{
    MessageBoxW(NULL, szCmdLine, L"Title", MB_OK);

    return EXIT_SUCCESS;
}
</pre>

<p>
This code shows a small message box on the screen. It shows the first command
line argument. The argument can be supplied on the command line, or in the
Project options on the General tab. There is an edit box called Command line
arguments, where we can supply our command line arguments too. 
</p>

<pre class="explanation">
int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
               PWSTR szCmdLine, int CmdShow)
</pre>

<p>
The third parameter of the <code>wWinMain()</code> function is a 
PWSTR (pointer to wide string). It accepts wide characters.
</p>

<img src="/img/gui/winapi/mbox.png" alt="A message box">
<div class="figure">Figure: A message box</div>

                          
<p>
In this part of the Winapi tutorial, we have mentioned main functions. 
</p>


<div class="center"> 
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* horizontal */
google_ad_slot = "1734478269";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 
</div> 
<br> 


<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified September 17, 2012  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>
